refactor: remove deprecated shield registration endpoints by leseb · Pull Request #5291 · llamastack/llama-stack

leseb · 2026-03-25T15:56:24Z

Summary

Remove the deprecated POST /v1/shields (register) and DELETE /v1/shields/{identifier} (unregister) HTTP endpoints. Shields should be registered via distribution config, not runtime API calls.

What's removed

POST /v1/shields - register_shield endpoint (was already deprecated=True)
DELETE /v1/shields/{identifier} - unregister_shield endpoint (was already deprecated=True)
Stainless config references to the removed endpoints

What's kept (and why)

Component	Why it stays
`GET /v1/shields`	Runtime inspection - needed to check what shields are available
`GET /v1/shields/{id}`	Shield lookup - used by moderations and guardrails internally
`POST /v1/moderations`	OpenAI-compatible content moderation endpoint
Guardrail hooks in Responses	Production safety - `run_guardrails()` validates input/output on every response when `guardrail_ids` is set
Safety providers (Llama Guard, code scanner, prompt guard)	Backends for `/v1/moderations` and guardrails
`ShieldToModerationMixin`	Bridges shield providers to the OpenAI moderations API

How /v1/moderations works

Client -> POST /v1/moderations {input: "text", model: "shield-id"}
  -> SafetyRouter.run_moderation()
    -> ShieldToModerationMixin.run_moderation()
      -> provider.run_shield() (e.g. Llama Guard)
    -> ModerationObject {flagged: bool, categories: {...}}

The entire chain depends on the safety providers and shield routing table being available.

How guardrails in Responses work

Client -> POST /v1/responses {guardrail_ids: ["llama-guard"]}
  -> ResponsesOrchestrator
    -> run_guardrails(safety_api, input_text, guardrail_ids)  # input check
    -> LLM call
    -> run_guardrails(safety_api, output_text, guardrail_ids)  # output check

Guardrails provide inline safety validation without a separate API call.

Test plan

Unit tests pass (CLI test updated to use vector_io instead of safety)
Pre-commit passes
API spec regenerated

🤖 Generated with Claude Code

Remove the deprecated Safety and Shields APIs entirely from llama-stack. This includes: - API packages (llama_stack_api/safety/, llama_stack_api/shields/) - Provider implementations (inline: llama-guard, prompt-guard, code-scanner; remote: bedrock, nvidia, sambanova, passthrough) - Provider registry (providers/registry/safety.py) - Router and routing table (core/routers/safety.py, core/routing_tables/shields.py) - Api enum values (Api.safety, Api.shields) - SafetyConfig, ShieldWithOwner, ShieldsProtocolPrivate from core datatypes - Distribution YAML configs (safety providers, shields registered resources, safety config sections, run-with-safety.yaml files) - Distribution template code (get_shield_registry, default_shields, safety_config) - Agent/responses guardrail execution code (run_guardrails, extract_guardrail_ids, safety_api parameter threading, input/output guardrail checks in streaming) - Telemetry helpers and constants for safety - All safety-related unit and integration tests - ShieldToModerationMixin utility The guardrails parameter in create_openai_response is preserved in the signature but is now a no-op. The Responses API continues to work without safety. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

github-actions · 2026-03-25T15:57:08Z

✱ Stainless preview builds

This PR will update the llama-stack-client SDKs with the following commit message.

refactor!: remove Safety/Shields API and all connected code

Edit this comment to update it. It will appear in the SDK's changelogs.

✅ llama-stack-client-node studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️ → build ✅ → lint ✅ → test ✅
npm install https://pkg.stainless.com/s/llama-stack-client-node/8d05f8b9d9dfe891a741b3622f6ce1db8436725d/dist.tar.gz

✅ llama-stack-client-go studio · conflict

Your SDK build had a "fatal" conclusion in the base build, which improved to "merge_conflict", but this did not represent a regression.

⚡ llama-stack-client-python studio · conflict

Your SDK build resulted in a merge conflict between your custom code and the newly generated changes, which is a regression from the base state.
You don't need to resolve this conflict right now, but you will need to resolve it for your changes to be released to your users. Read more about why this happened here.

✅ llama-stack-client-openapi studio · code · diff

Your SDK build had at least one "warning" diagnostic, but this did not represent a regression.
generate ⚠️

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-04-02 14:02:46 UTC

mergify · 2026-03-25T15:57:43Z

This pull request has merge conflicts that must be resolved before it can be merged. @leseb please rebase it. https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

Signed-off-by: Sébastien Han <seb@redhat.com>

Resolve merge conflicts from upstream/main, primarily around the agents-to-responses API rename (PR llamastack#5195) and new upstream changes. The key resolutions were updating Api.agents to Api.responses in datatypes.py and resolver.py, removing reintroduced safety/shields references from OCI and WatsonX distributions, fixing the stainless config to remove safety/shields/moderations endpoints, and regenerating all OpenAPI specs, distribution configs, and coverage documentation. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

Merge upstream/main into remove-safety-api, resolving conflicts by keeping the safety API removal from this branch. All modify/delete conflicts for safety-related files (shields, safety providers, safety router, safety registry) were resolved by accepting the deletion. Content conflicts in core/datatypes.py, core/stack.py, distributions/template.py, and llama_stack_api/datatypes.py were resolved by removing the safety-related code (ShieldWithOwner, ShieldsProtocolPrivate, validate_safety_config, get_shield_registry) that upstream had modified but this branch intentionally removes. Signed-off-by: Sébastien Han <seb@redhat.com>

mergify · 2026-03-26T20:17:56Z

This pull request has merge conflicts that must be resolved before it can be merged. @leseb please rebase it. https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

Accept upstream's updated OpenAI API conformance data including the new Moderations category and updated summary statistics (28/146 endpoints, 87.8% conformance score). These are auto-generated documentation files tracking OpenAI API coverage which are unrelated to the Llama Stack Safety/Shields API removal in this branch. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

The pre-commit hook regenerated conformance data to reflect the actual endpoints available in this branch (27/146 endpoints, 89.0% conformance score) since the Moderations endpoint is not present after the Safety API removal. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

- Add "agentic" to tagline per franciscojavierarceo suggestion - Remove Safety/Moderations (being removed in llamastack#5291) - Use uv instead of pip in install instructions - Remove Swift and Kotlin from SDK table - Fix "semantic search" to just "search" for vector stores - Mention non-OpenAI APIs (Prompts, File Processors) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

Resolve modify/delete conflicts for dell distribution files that were deleted upstream. Accept the upstream deletion since the dell distribution was removed in main. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

Resolve merge conflicts in generated conformance documentation files (conformance.mdx and openai-coverage.json) by accepting upstream values and letting the pre-commit hook regenerate with the correct scores for this branch. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

Resolve merge conflicts from upstream splitting test_openai_responses.py into smaller focused modules. The split file was deleted (upstream) and modified (this branch), so we accept the upstream deletion since the new split files are present. Remove safety_api references from the new test files to align with this branch's removal of the Safety API. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

mergify · 2026-03-30T14:04:49Z

This pull request has merge conflicts that must be resolved before it can be merged. @leseb please rebase it. https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

Resolve merge conflicts from upstream safety-related changes (guardrails, validate_safety_config, safety routers and providers) by keeping them deleted, consistent with this branch's goal of removing the Safety/Shields API entirely. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

mergify · 2026-03-30T14:39:59Z

This pull request has merge conflicts that must be resolved before it can be merged. @leseb please rebase it. https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

Resolve merge conflicts in fastapi_router_registry.py and llama_stack_api/__init__.py. Take upstream's auto-discovery approach for router factories which replaces the hardcoded dict. Drop the ViolationLevel export from __init__.py since the Safety API is removed in this branch. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

Merge upstream/main into remove-safety-api branch. Resolved conflict in streaming.py by taking upstream's ServiceTier wrapping while dropping safety_identifier. Also removed safety_identifier references that upstream added since the last merge, as this branch removes all safety-related code. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

Take upstream's updated test coverage score (44.1%) while merging the remove-safety-api branch changes. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

The OpenAI coverage pre-commit hook regenerated the conformance documentation to reflect the current integration test coverage score. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

Resolve merge conflicts in the OpenAI conformance documentation. The Moderations section added by upstream was removed since this branch removes the Safety/Shields API. The Responses section from upstream was kept as it is not safety-related and contains updated conformance data without safety_identifier references. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

…fety code Merge upstream/main into remove-safety-api branch, resolving conflicts in docs/docs/api-openai/provider_matrix.md and streaming.py. Took upstream's updated test numbers and ollama provider column, but removed safety_identifier test rows. Removed the violation_detected check, _create_refusal_response method, guardrails parameter, and safety-related docstring that were auto-merged from upstream since this branch removes the Safety/Shields API. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

Remove guardrails parameter, ResponseGuardrailSpec/ResponseGuardrail types, _create_refusal_response method, and safety-related integration tests that were auto-merged from upstream. These additions are incompatible with this branch which removes the Safety/Shields API entirely. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

Regenerate OpenAPI specifications to reflect the removal of ResponseGuardrailSpec and guardrails field from the API models. Fix linting in test_responses_errors.py for unused import. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

The merge with upstream/main re-introduced the Agents import in stack.py which was removed as part of the safety API removal. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

Replace agents with responses in postgres-demo distribution config. Remove shield_id test (shields removed), replace with vector_store_id. Remove safety_api parameter from streaming test fixture. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

Tables now have rounded corners, subtle zebra striping, hover highlights, purple-tinted headers, and cleaner borders. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

mergify · 2026-04-01T20:30:57Z

This pull request has merge conflicts that must be resolved before it can be merged. @leseb please rebase it. https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

Merge upstream/main into remove-safety-api branch. Resolved conflicts in the OpenAPI spec files (llama-stack-spec.yaml, stainless-llama-stack-spec.yaml, and client-sdks/stainless/openapi.yml) by keeping the new code samples from upstream while removing the safety-related endpoints (/v1/moderations and /v1/safety/run-shield) that upstream added. Also removed the moderations code sample from scripts/openapi_generator/code_samples.py to stay consistent with the safety API removal. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

The merge conflict resolution joined lines incorrectly in the spec files, causing duplicate mapping keys. This commit applies the codegen fix to properly separate the code sample endings from the next path entries. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

Replace Api.safety/llama-guard with Api.vector_io/faiss in test_stack_list_deps.py since the safety API no longer exists. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

Keep the OpenAI-compatible /v1/moderations endpoint and the guardrail integration in the Responses orchestrator. Only remove the standalone shield management APIs (register/unregister/list shields). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

Remove the deprecated POST /v1/shields (register_shield) and DELETE /v1/shields/{identifier} (unregister_shield) HTTP endpoints. Shields should be registered via distribution config, not runtime API calls. Keep: - GET /v1/shields (list) and GET /v1/shields/{id} (retrieve) - needed for runtime inspection and moderations config validation - POST /v1/moderations - OpenAI-compatible content moderation endpoint - Guardrail hooks in the Responses orchestrator (run_guardrails, safety_api, guardrail_ids) - production safety integration - All safety providers (Llama Guard, code scanner, prompt guard) - needed for /v1/moderations and guardrails to function Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

Remove the 'guardrails' field from the CreateResponseRequest schema. The feature still works via extra_body, which is how integration tests and documentation already pass it. This improves OpenAI API conformance since guardrails is a Llama Stack extension, not part of the OpenAI Responses API spec. Before (Llama Stack client): client.responses.create(guardrails=["llama-guard"], ...) After (any OpenAI client): client.responses.create(extra_body={"guardrails": ["llama-guard"]}, ...) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

meta-cla bot added the CLA Signed This label is managed by the Meta Open Source bot. label Mar 25, 2026

leseb added this to the 0.8.0 milestone Mar 25, 2026

mergify bot added the needs-rebase label Mar 25, 2026

Merge remote-tracking branch 'upstream/main' into remove-safety-api

3005348

Signed-off-by: Sébastien Han <seb@redhat.com>

mergify bot removed the needs-rebase label Mar 25, 2026

leseb and others added 3 commits March 25, 2026 18:09

fix: resolve agents→responses rename in fastapi_router_registry

2365f1c

Signed-off-by: Sébastien Han <seb@redhat.com>

gyliu513 mentioned this pull request Mar 26, 2026

docs: rewrite README and docs to lead with OpenAI API compatibility #5323

Merged

3 tasks

mergify bot added the needs-rebase label Mar 26, 2026

leseb and others added 2 commits March 26, 2026 21:23

mergify bot removed the needs-rebase label Mar 26, 2026

leseb and others added 3 commits March 27, 2026 11:53

Merge branch 'main' into remove-safety-api

de1b8a1

eoinfennessy mentioned this pull request Mar 30, 2026

feat: Introduce v1alpha2 version of LlamaStackDistribution CRD llamastack/llama-stack-k8s-operator#253

Open

leseb and others added 2 commits March 30, 2026 15:10

chore: regenerate openai-coverage.json after merge

9b67c5e

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

mergify bot added the needs-rebase label Mar 30, 2026

mergify bot removed the needs-rebase label Mar 30, 2026

mergify bot added the needs-rebase label Mar 30, 2026

mergify bot removed the needs-rebase label Mar 30, 2026

leseb and others added 16 commits March 31, 2026 15:22

fix: regenerate OpenAPI specs after removing safety_identifier

db5f28e

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

fix: update OpenAI coverage baseline and provider compatibility matrix

6d71804

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

merge: resolve conflict with upstream/main in conformance.mdx

ec79a86

Take upstream's updated test coverage score (44.1%) while merging the remove-safety-api branch changes. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

fix: regenerate conformance.mdx via pre-commit hook

a9d1565

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

Merge remote-tracking branch 'upstream/main' into remove-safety-api

9227733

chore: remove starter-gpu distribution leftover from merge

144514b

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

mergify bot added the needs-rebase label Apr 1, 2026

leseb and others added 2 commits April 1, 2026 22:36

mergify bot removed the needs-rebase label Apr 1, 2026

leseb and others added 5 commits April 2, 2026 11:16

Merge remote-tracking branch 'upstream/main' into remove-safety-api

b338079

chore: regenerate specs after shield endpoint removal

ea62872

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

leseb changed the title ~~refactor!: remove Safety/Shields API and all connected code~~ refactor: remove deprecated shield registration endpoints Apr 2, 2026

leseb and others added 2 commits April 2, 2026 15:59

chore: regenerate specs after guardrails field removal

a20400a

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Sébastien Han <seb@redhat.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor: remove deprecated shield registration endpoints#5291

refactor: remove deprecated shield registration endpoints#5291
leseb wants to merge 41 commits intollamastack:mainfrom
leseb:remove-safety-api

leseb commented Mar 25, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 25, 2026 •

edited

Loading

Uh oh!

mergify bot commented Mar 25, 2026

Uh oh!

mergify bot commented Mar 26, 2026

Uh oh!

mergify bot commented Mar 30, 2026

Uh oh!

mergify bot commented Mar 30, 2026

Uh oh!

mergify bot commented Apr 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

leseb commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What's removed

What's kept (and why)

How /v1/moderations works

How guardrails in Responses work

Test plan

Uh oh!

github-actions bot commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✱ Stainless preview builds

Uh oh!

mergify bot commented Mar 25, 2026

Uh oh!

mergify bot commented Mar 26, 2026

Uh oh!

mergify bot commented Mar 30, 2026

Uh oh!

mergify bot commented Mar 30, 2026

Uh oh!

mergify bot commented Apr 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

leseb commented Mar 25, 2026 •

edited

Loading

github-actions bot commented Mar 25, 2026 •

edited

Loading